site: maturity pass + amesh-agent binary pipeline - #17

The @authmesh/agent package currently fails to run after 'npm install'
on every platform, not just Raspberry Pi. The agent uses Bun.spawn with
the terminal PTY option (Bun-only), and the runtime guard at
packages/agent/src/commands/agent/start.ts fires under Node.js. Users
have to manually wrap it with 'bun $(which amesh-agent) agent start',
which is a terrible onboarding experience.

This commit ships prebuilt binaries for all four Bun-supported targets
(darwin-arm64, darwin-x64, linux-x64, linux-arm64) so 'npm install' and
'brew install' both produce a working amesh-agent on those platforms.
Linux armv7 (Raspberry Pi 3 and earlier) remains unsupported because
Bun itself does not ship for that architecture.

Compiled binary entry point
- New packages/agent/src/sea.ts mirrors packages/cli/src/sea.ts:
  statically imports all commands so oclif's filesystem discovery
  doesn't need a real package.json at runtime (Bun compiled binaries
  can't read /$bunfs). Adds nested-command dispatch for
  'amesh-agent agent start' since the CLI sea.ts only handled
  top-level commands.

Build pipeline
- packaging/build-bun.mjs: refactored to a compile() helper invoked
  twice, once for amesh (packages/cli/src/sea.ts) and once for
  amesh-agent (packages/agent/src/sea.ts). Both binaries land in
  packaging/dist/, respecting --target for cross-compilation.
  Verified locally: produces dist/amesh and dist/amesh-agent, each
  ~61MB, --help and nested 'agent start --help' dispatch correctly.

Release workflow
- .github/workflows/release-packages.yml: add bun-linux-arm64 to the
  matrix (cross-compiled from ubuntu-latest via Bun's --target flag).
  Each tarball already packs everything in packaging/dist/, so both
  binaries ship in the same amesh-{version}-{platform}-{arch}.tar.gz
  artifact — no new artifact count. Homebrew formula heredoc updated
  to include on_linux/on_arm block and install amesh-agent.

Homebrew formula
- packaging/homebrew/amesh.rb: install amesh-agent alongside amesh
  (guarded with File.exist? so releases without an agent binary don't
  break). Test block asserts both binaries respond to --help.

npm postinstall binary download
- packages/agent/package.json: bin now points at
  scripts/launcher.mjs instead of dist/index.js; adds postinstall
  running scripts/postinstall.mjs. Includes scripts/ in 'files'.
- New packages/agent/scripts/postinstall.mjs: detects
  process.platform + process.arch, maps to the matching GitHub
  release tarball, downloads via native fetch (Node 18+), extracts
  just the amesh-agent binary into bin/, chmods it 0755. Honors
  AMESH_SKIP_POSTINSTALL=1 escape hatch. On unsupported platforms
  (e.g. linux-armv7), prints a helpful 'install Bun and use wrapper'
  warning and exits 0 so 'npm install' never fails on unsupported
  archs — the JS entry + existing Bun guard still work as a fallback.
- New packages/agent/scripts/launcher.mjs: if the prebuilt binary
  exists in bin/, spawnSync it with passthrough args and exit with
  its status; otherwise fall back to the oclif JS entry which
  surfaces the Bun runtime requirement. Same pattern esbuild/swc use.

Per-package README fixes
- packages/agent/README.md: drop phantom Homebrew tap reference,
  document the postinstall binary download and the four supported
  platforms, explain armv7 limitation.
- packages/cli/README.md: remove incorrect 'amesh agent start' line
  (that command lives in @authmesh/agent, not @authmesh/cli) and add
  a note pointing to the separate agent package.

Not yet done (follow-up after first tagged release with these
changes)
- Re-add the Homebrew and binary tarball install options to
  /docs/remote-shell once binaries are actually in a release.
- Remove the amber 'Runtime requirement' callout added in the
  companion commit.
- Verify 'npm install -g @authmesh/agent' on fresh Ubuntu 22.04 x64
  and Debian aarch64 VMs.

…arator

The agent package ships with nested commands ('amesh-agent agent start'),
but oclif v4 defaults to colon-only syntax unless topicSeparator is set
explicitly. Without it, 'amesh-agent agent start' under the JS entry
point (dist/index.js, used as the postinstall fallback path) falls back
to oclif's topic help text and never invokes the command — meaning the
Bun runtime guard never fires, and users on unsupported platforms see
topic help instead of the clear 'install Bun and use the wrapper' error.

Adding topicSeparator: ' ' makes oclif treat space-separated args the
same as colon-separated, matching every code path and every doc
reference. Verified in a fresh Debian/Node container:

  node scripts/launcher.mjs agent start
    -> fires the Bun runtime guard (expected)

  node scripts/launcher.mjs agent start --help
    -> prints full command help with all flags (not topic help)

The compiled binary path (packages/agent/src/sea.ts) is unaffected —
it has its own explicit nested dispatch and already handles space
syntax. This fix is specifically for the JS fallback path that
triggers when postinstall can't download a binary for the host
architecture (e.g. linux-armv7).

Three internal docs were stale relative to the landpage changes and the
@authmesh/agent package split. Fixed in the same PR because they're
linked from the top-level README and ADRs visible to contributors.

docs/why-amesh.md: genericize company/competitor mentions
- Remove 'Uber, Samsung, Toyota, and Twitch' leak-victim list; replace
  with 'real engineers at companies of every size'.
- Remove 'AWS Secrets Manager, HashiCorp Vault, and Doppler' naming;
  rewrite the secrets-managers section to critique the pattern (string
  still copyable, runtime dependency, self-referential auth) rather
  than specific products. Add an acknowledgement that secrets managers
  are a genuine improvement over loose .env files — amesh operates at
  a different layer.
- Table row 'Vault access, Slack threads' -> 'secrets manager access,
  Slack threads'.

Matches the same cleanup already applied to the landpage blog post,
/docs/introduction, /docs/faq, and /docs/+page.svelte.

docs/remote-shell-spec.md: command name matches package split
- 9 references of 'amesh agent start' / 'amesh agent' corrected to
  'amesh-agent agent start' / 'amesh-agent agent' since the daemon
  now ships in @authmesh/agent, not @authmesh/cli.
- Added a pointer from section 5.1 to ADR-011 explaining the package
  split rationale.

docs/architecture-decisions.md: mark ADR-011 partially superseded
- Add a status block at the top of 'ADR-011: Remote shell in the CLI
  with explicit shell permission' explaining that the 'one package,
  one binary' design was reversed: the daemon is now in @authmesh/agent
  exposing amesh-agent, while @authmesh/cli keeps the controller-side
  commands. The reason is runtime-dependency: Bun.spawn({ terminal })
  is Bun-only, and bundling it with @authmesh/cli forced the entire
  controller install to depend on Bun even for users who only wanted
  amesh init + amesh.fetch().
- Strike through the 'rejected alternative' bullet that argued against
  a separate package (historical record preserved, with an inline
  explanation of why it was later reversed).
- The security argument in the ADR body is unchanged — 'amesh grant
  --shell' is still the real boundary, not the package boundary.

Preserved as historical records, not touched:
- docs/remote-shell-security-review.md (security review snapshot)
- docs/project-review-2026-04-02.md (project review snapshot)